Order Notification API
JWT validation
Chorus will provide a JSON Web Token (JWT) in the header of every notification message sent to your POST /orderNotification endpoint. This JWT needs to be validated to confirm that the message has been sent by Chorus and is intended for you.
Note: To avoid unexpected activity, we recommend you apply proper security practices to ensure the initial processing and validation of the notification is isolated from your core system processing.
Signature validation
The signature on the JWT can be validated using the JSON Web Key Set (JWKS) available on the Microsoft keystore. To perform the validation of the JWT provided as part of the header, use the following values in the header:
- kid
- x5t
Note: As Microsoft constantly updates keys, use the latest version of the JWKS for validation of the JWT.
Scope and environment
The following table provides the scopes used to access each environment for the Order Notification API.
| Environment | Order Notification API scope |
|---|---|
| Production | api://ordernotification |
| Production EMMA | api://ordernotification-sandbox |
JWT fields
The following table provides the details you will need to validate in the JWT provided by Chorus.
| JWT field | Expected value |
|---|---|
| aud | Order Notification API scope for the relevant environment. |
| iss | https://sts.windows.net/41360c96-1755-4bf8-8527-81bb0ad2ac43/ |
| idp | https://sts.windows.net/41360c96-1755-4bf8-8527-81bb0ad2ac43/ |
| iat | Datetime value prior to the current time. |
| nbf | Datetime value prior to the current time. |
| exp | Datetime value after the current time. |
| roles.customerRef | Your customer reference value in the following format: customerRef:<customerRef> |